home *** CD-ROM | disk | FTP | other *** search
/ El Mac 7 / El Mac 7.iso / De la revista / Ghostscript / files / dll.doc < prev    next >
Encoding:
Text File  |  1994-04-25  |  13.2 KB  |  372 lines  |  [TEXT/ttxt]
  1. /* Copyright (C) 1994, Russell Lang.  All rights reserved.
  2.   
  3.   This file is part of Aladdin Ghostscript.
  4.   
  5.   Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  6.   or distributor accepts any responsibility for the consequences of using it,
  7.   or for whether it serves any particular purpose or works at all, unless he
  8.   or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  9.   License (the "License") for full details.
  10.   
  11.   Every copy of Aladdin Ghostscript must include a copy of the License,
  12.   normally in a plain ASCII text file named PUBLIC.  The License grants you
  13.   the right to copy, modify and redistribute Aladdin Ghostscript, but only
  14.   under certain conditions described in the License.  Among other things, the
  15.   License requires that the copyright notice and this notice be preserved on
  16.   all copies.
  17. */
  18.  
  19. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  20.  
  21. This file, dll.doc, describes how to use the Ghostscript Dynamic
  22. Link Library.
  23.  
  24. For an overview of Ghostscript and a list of the documentation files, see
  25. README.  
  26.  
  27. ==================================
  28. DLL.DOC   1994-07-03
  29. ==================================
  30.  
  31. This document describes work in progress.
  32.  
  33. It is proposed to implement Ghostscript as a dynamic link library 
  34. for OS/2, Win32s and Win16.
  35. At present the OS/2, Win32s and Win16 DLLs are partially operational.
  36.  
  37. The Win16 DLL (GSDLL16.DLL) is a large memory model DLL with far 
  38. static data.  Due to the limitations of 16 bit MS-Windows, the DLL 
  39. can used by only one program at a time.  
  40.  
  41. The Win32s DLL (GSDLL32.DLL) has MULTIPLE NONSHARED data segments.
  42. Under Win32s it can be used by only one program at a time.
  43. Under Windows NT it is hoped that it can be called by multiple programs.
  44.  
  45. The OS/2 DLL (GSDLL2.DLL) has MULTIPLE NONSHARED data segments and
  46. so it can be called by multiple programs.
  47.  
  48. The interface to the DLL consists of 5 functions, 1 provided by 
  49. the caller and the other 4 by the DLL.
  50.  
  51. =============
  52. DLL functions
  53. =============
  54. The four functions provided by the DLL are:
  55.   int WINAPI gsdll_revision(char **product, char **copyright, 
  56.     long *gs_revision, long *gs_revisiondate)
  57.   int WINAPI gsdll_init(GSDLL_CALLBACK callback, char *str);
  58.   int WINAPI gsdll_execute(char *str);
  59.   int WINAPI gsdll_exit(void);
  60. For OS/2, WINAPI is defined as
  61.   #define WINAPI
  62.  
  63. ----------------
  64. gsdll_revision()
  65. ----------------
  66. This returns the revision numbers and strings of the Ghostscript DLL.
  67. This function may be called before gsdll_init().
  68. An example:
  69.   char *product;
  70.   char *copyright;
  71.   long revision;
  72.   long revisiondate;
  73.   gsdll_revision(&product, ©right, &revision, &revisiondate);
  74. NULL pointers may be used if you do not want a particular value.
  75.  
  76. ------------
  77. gsdll_init()
  78. ------------
  79. The first function gsdll_init() must be called after loading
  80. the DLL and before executing any ghostscript commands.
  81. The arguments are the address of the callback function and
  82. a string containing a subset of the Ghostscript command line
  83. options.  The command line options must be separated by a null
  84. character and terminated by two nulls.
  85. The options supported are:
  86.   -Ipath
  87.   -dname
  88.   -dname=value
  89.   -sname=string
  90. For example
  91.   code = gsdll_init(gsdll_callback,
  92.            "-Ic:\\gs;c:\\gs\\fonts\0-dNOPAUSE\0-sDEVICE=djet500\0");
  93.  
  94. If the return code is non-zero then the DLL should be immediately
  95. unloaded or the caller terminated.  gsdll_exit() must not be called.
  96.  
  97. ---------------
  98. gsdll_execute()
  99. ---------------
  100. After successfully calling gsdll_init(), commands may be given to 
  101. Ghostscript with gsdll_execute().  Examples are:
  102.   code = gsdll_execute("1 2 add == flush");
  103.   code = gsdll_execute("quit");
  104. return code is zero if there are no errors.
  105. return code is less than zero if an error has occured.
  106. return code is less than or equal to -100 if "quit" has been 
  107. executed or a fatal error has occured.  gsdll_exit() must 
  108. then be called and the DLL unloaded.
  109. gsdll_execute does not flush stdio - if you want to see output from
  110. Ghostscript you must do this explicitly as shown in the example above.
  111.  
  112. ----------
  113. gsdll_exit
  114. ----------
  115. To terminate the Ghostscript DLL, gsdll_exit() is called.
  116. This must be called if a fatal error has occured (see return
  117. value of gsdll_execute).
  118. After calling gsdll_exit(), the DLL must be unloaded, either
  119. by terminating the application or by calling DosFreeModule (OS/2)
  120. or FreeLibrary (MS-Windows).
  121.  
  122.  
  123. =================
  124. Callback function
  125. =================
  126. A callback function must be provided by the caller and given
  127. as an argument to gsdll_init().
  128. The callback function is called by the DLL for stdio and to notify 
  129. the caller about device events.
  130.  
  131. The function provided by the caller has the following prototype:
  132.   int gsdll_callback(int message, char *str, unsigned long count);
  133.  
  134. An example callback function is:
  135.     int 
  136.     gsdll_callback(int message, char *str, unsigned long count)
  137.     {
  138.     char *p;
  139.         switch (message) {
  140.             case GSDLL_STDIN:
  141.                 p = fgets(str, count, stdin);
  142.                 if (p)
  143.                     return strlen(str);
  144.                 else
  145.                     return 0;
  146.             case GSDLL_STDOUT:
  147.                 if (str != (char *)NULL)
  148.                     fwrite(str, 1, count, stdout);
  149.                 return count;
  150.             case GSDLL_DEVICE:
  151.                 fprintf(stdout,"Callback: DEVICE %p %s\n", str,
  152.                     count ? "open" : "close");
  153.                 break;
  154.             case GSDLL_SYNC:
  155.                 fprintf(stdout,"Callback: SYNC %p\n", str);
  156.                 break;
  157.             case GSDLL_PAGE:
  158.                 fprintf(stdout,"Callback: PAGE %p\n", str);
  159.                 break;
  160.             case GSDLL_SIZE:
  161.                 fprintf(stdout,"Callback: SIZE %p width=%d height=%d\n", str,
  162.                     (int)(count & 0xffff), (int)((count>>16) & 0xffff) );
  163.                 break;
  164.             default:
  165.                 fprintf(stdout,"Callback: Unknown message=%d\n",message);
  166.                 break;
  167.         }
  168.         return 0;
  169.     }
  170.  
  171.  
  172. The messages used by the callback are:
  173.   #define GSDLL_STDIN 1   /* get count characters to str from stdin */
  174.                           /* return number of characters read */
  175.   #define GSDLL_STDOUT 2  /* put count characters from str to stdout*/
  176.                           /* return number of characters written */
  177.   #define GSDLL_DEVICE 3  /* device = str has been opened if count=1 */
  178.                           /*                    or closed if count=0 */
  179.   #define GSDLL_SYNC 4    /* sync_output for device str */ 
  180.   #define GSDLL_PAGE 5    /* output_page for device str */
  181.   #define GSDLL_SIZE 6    /* resize for device str */
  182.                           /* LOWORD(count) is new xsize */
  183.                           /* HIWORD(count) is new ysize */
  184.  
  185. ==========================
  186. Example DLL usage for OS/2
  187. ==========================
  188. The following example shows a minimal usage of the Ghostscript DLL.
  189. The example callback function above is needed.
  190.  
  191. #define INCL_DOS
  192. #include <os2.h>
  193. #include <stdio.h>
  194. #include "gsdll.h"
  195. typedef int (*PFN_gsdll_init)(GSDLL_CALLBACK, char *);
  196. typedef int (*PFN_gsdll_exit)(void);
  197. typedef int (*PFN_gsdll_execute)(char *);
  198.  
  199. PFN_gsdll_init pgsdll_init;
  200. PFN_gsdll_exit pgsdll_exit;
  201. PFN_gsdll_execute pgsdll_execute;
  202.  
  203. HMODULE hmodule_gsdll;
  204. char buf[256];
  205.  
  206. int
  207. main(int argc, char *argv[])
  208. {
  209. int code;
  210. APIRET rc;
  211.     if (!DosLoadModule(buf, sizeof(buf), "GSDLL2", &hmodule_gsdll)) {
  212.         fprintf(stderr, "Loaded GSDLL2\n");
  213.         DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_init", (PFN *)(&pgsdll_init));
  214.         DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_exit", (PFN *)(&pgsdll_exit));
  215.         DosQueryProcAddr(hmodule_gsdll, 0, "gsdll_execute", (PFN *)(&pgsdll_execute));
  216.     }
  217.     else {
  218.         fprintf(stderr, "Can't load GSDLL2\n");
  219.     }
  220.  
  221.     code = (*pgsdll_init)(gsdll_callback, "-dNODISPLAY\0");
  222.     fprintf(stdout,"gsdll_init returns %d\n", code);
  223.     if (code==0) {
  224.         while (fgets(buf, sizeof(buf), stdin)) {
  225.             code = (*pgsdll_execute)(buf);
  226.             fprintf(stdout,"gsdll_execute returns %d\n", code);
  227.         if (code < 0)
  228.            break;
  229.         }
  230.         code = (*pgsdll_exit)();
  231.         fprintf(stdout,"gsdll_exit returns %d\n", code);
  232.     }
  233.     rc = DosFreeModule(hmodule_gsdll);
  234.     fprintf(stdout,"DosFreeModule returns %d\n", rc);
  235.     return 0;
  236. }
  237.  
  238. ===============================
  239. Ghostscript DLL device for OS/2
  240. ===============================
  241. The os2dll device is provided in the Ghostscript DLL for use
  242. by the caller.  No drawing facilities are provided by the DLL
  243. because the DLL may be loaded by a text only (non PM) application.
  244.  
  245. The caller will be notified via the gsdll_callback when a new
  246. os2dll device is opened or closed (GSDLL_DEVICE), when the window 
  247. should be redrawn (GSDLL_SYNC or GSDLL_PAGE) or when the bitmap 
  248. size changes (GSDLL_SIZE).
  249.  
  250. Two DLL functions are available for accessing the os2dll device:
  251.  
  252. ----------------
  253. gsdll_get_bitmap
  254. ----------------
  255. The following function returns a pointer to a bitmap in BMP format.
  256. The os2dll device draws into this bitmap.
  257.  
  258. unsigned long gsdll_get_bitmap(unsigned char *device, unsigned char **pbitmap);
  259.  /* return in pbitmap the address of the bitmap */
  260.  /* device is a pointer to Ghostscript os2dll device from GSDLL_DEVICE message */
  261.  
  262. The caller can then display the bitmap however it likes, but should 
  263. lock the bitmap with gsdll_lock_bitmap() before painting from it, 
  264. and unlock it afterwards.
  265.  
  266. -----------------
  267. gsdll_lock_bitmap
  268. -----------------
  269. Since the caller is likely to be multithreaded, a mutex is needed
  270. to prevent access to the bitmap while it's size is being changed.
  271. This is accessed via the following function.
  272.  
  273. unsigned long gsdll_lock_bitmap(unsigned char *device, int flag);
  274.  /* Lock the bitmap (so it's size cannot be changed) if flag = TRUE */
  275.  /* or unlock the bitmap if flag = FALSE */
  276.  /* device is a pointer to Ghostscript os2dll device from GSDLL_DEVICE message */
  277.  
  278. This function will block until the bitmap is locked.
  279.  
  280. To lock the bitmap use
  281.   gsdll_lock_bitmap(device, 1);
  282. To unlock the bitmap use
  283.   gsdll_lock_bitmap(device, 0);
  284.  
  285. This function is typically used to lock the bitmap while
  286. repainting a window.
  287.  
  288. =====================================
  289. Ghostscript DLL device for MS-Windows
  290. =====================================
  291. The mswindll device is provided in the Ghostscript DLL for use
  292. by the caller.  
  293.  
  294. The caller will be notified via the gsdll_callback when a new
  295. mswindll device is opened or closed (GSDLL_DEVICE), when the window 
  296. should be redrawn (GSDLL_SYNC or GSDLL_PAGE) or when the bitmap 
  297. size changes (GSDLL_SIZE).
  298.  
  299. Three DLL functions are available for accessing the mswindll device:
  300.  
  301. --------------
  302. gsdll_copy_dib
  303. --------------
  304. This function is commonly used when copying the mswindll bitmap
  305. to the clipboard.
  306.  
  307. /* make a copy of the device bitmap and return shared memory handle to it */
  308. /* device is a pointer to Ghostscript device from GSDLL_DEVICE message */
  309. HGLOBAL WINAPI gsdll_copy_dib(unsigned char *device);
  310.  
  311. ------------------
  312. gsdll_copy_palette
  313. ------------------
  314. This function can be used when copying the mswindll palette
  315. to the clipboard.
  316.  
  317. /* make a copy of the device palette and return a handle to it */
  318. /* device is a pointer to Ghostscript device from GSDLL_DEVICE message */
  319. HPALETTE WINAPI gsdll_copy_palette(unsigned char *device);
  320.  
  321. ----------
  322. gsdll_draw
  323. ----------
  324. This function is meant to be used for displaying output from the
  325. mswindll device.  The caller should create a window and call 
  326. gsdll_draw in response to the WM_PAINT message.
  327. The device context hdc must be for a device because
  328. SetDIBitsToDevice() is used.
  329.  
  330. /* copy the rectangle src from the device bitmap */
  331. /* to the rectangle dest on the device given by hdc */
  332. /* hdc must be a device context for a device (NOT a bitmap) */
  333. /* device is a pointer to Ghostscript device from GSDLL_DEVICE message */
  334. void WINAPI gsdll_draw(unsigned char *device, HDC hdc, LPRECT dest, LPRECT src);
  335.  
  336. ================
  337. MS-Windows 16bit
  338. ================
  339. This platform has the most problems of the three.
  340.  
  341. The Win16 DLL (GSDLL16.DLL) is a large memory model DLL with far 
  342. static data.  Due to the limitations of 16 bit MS-Windows, the DLL 
  343. can used by only one program at a time.
  344. However, GSDLL16 is marked as having SINGLE SHARED data segments which
  345. allows multiple applications to load GSDLL16.  (The DLL wouldn't load
  346. at all if MULTIPLE NONSHARED was used).  Applications loading GSDLL16
  347. should check the return value of gsdll_init().  If it is non-zero
  348. then GSDLL16 is already in use by another application and should NOT
  349. be used.  GSDLL16 should be unloaded immediately using FreeLibrary(),
  350. or the caller program should terminate.
  351.  
  352. The segmented architecture of the 80286 causes the usual amount of
  353. grief when using GSDLL16.
  354. Because the callback is called from the DLL which is using a different
  355. data segment, the callback must be declared as _far _export.
  356. Note that _pascal is not used:
  357.   int _far _export gsdll_callback(int message, char *str, unsigned long count);
  358. Instead of giving gsdll_init the address of gsdll_callback, it should
  359. instead be given the address of a thunk created by MakeProcInstance.
  360. This thunk changes the data segment back to that used by the caller:
  361.   FARPROC lpfnCallback;
  362.   lpfnCallback = (FARPROC)MakeProcInstance((FARPROC)gsdll_callback, hInstance);
  363.   code = (*pgsdll_init)((GSDLL_CALLBACK)lpfnCallback, "-dNODISPLAY\0");
  364.   if (!code) {
  365.       fprintf(stderr, "GSDLL16 is already in use\n");
  366.       return -1;
  367.   }
  368.  
  369. ====================
  370. /* end of dll.doc */
  371. ====================
  372.